home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 003 / _tar / Tar`Doc < prev   
Text File  |  1993-08-26  |  16KB  |  435 lines
  1.  
  2. tar - tape archive, version 1.1o, written for the Archimedes by
  3.  
  4.                     Frank Lancaster, 7-Nov-1991
  5.  
  6.  
  7. Bug reports and comments may be sent as e-mail to: fl@tools.uucp
  8. Paper Mail: Frank Lancaster
  9.             Tools GmbH
  10.             Kessenicher Str. 108
  11.             W-5300 Bonn 1
  12.             Federal Republic of Germany
  13.  
  14.  
  15. This programme is public domain. You may copy it freely, provided
  16. you do not charge ANYTHING for its distribution.
  17.  
  18.  
  19. Table of Contents
  20. -----------------
  21.  1. Introduction
  22.  2. Installation
  23.  3. Usage
  24.  4. Normal Files As Archives
  25.  5. Hard Disc Backup
  26.  6. Compression
  27.  7. The List File
  28.  8. UNIX Compatibility
  29.  9. Raw disc dumping
  30. 10. History
  31.  
  32.  
  33. 1. Introduction
  34. ---------------
  35. This version of tar is derived from the UNIX tar utility. Its main use
  36. is as a hard disk backup programme. It also comes in very handy when
  37. transferring files from or to UNIX. The name "tape archive" is misleading but
  38. historical. On the Archimedes archives are ordinary files on any
  39. file-system (adfs, scsi, dosfs, etc.). Multiple disc archives are supported,
  40. now also as ordinary files. Disk archives in ADFS D/E/L or MS-DOS (double-
  41. sided, 9 sectors) format dumped to raw disks are supported.
  42.  
  43.  
  44. 2. Installation
  45. ---------------
  46. If you have clib version 3.66, you can use the tar_clib and compr_clib
  47. versions of tar and compress.
  48. Before using the programme set the system variable "tar$scrap" to the
  49. name of a temporary scrap file which should only be used by tar,
  50. for example "adfs::4.$.tmp.scrap". The leaf name must not be longer than
  51. 8 characters, another 2 ("-Z") are added if compression is used.
  52. This file will only be used if compression is enabled.
  53. If compression is used tar requires the compress programme (included in
  54. this distribution), which handles compression and decompression. Normally
  55. this should be accessable via the system variable Run$Path, but you can
  56. customize the compression and decompression commands with the two system
  57. variables tar$compress and tar$decompress (see below "compression").
  58. The system variable tar$filetype is used as file type for tar files. If
  59. it is not set, file type FFD (data) is used.
  60.  
  61.  
  62. 3. Usage
  63. --------
  64. The programme should be called from the command line interpreter as it
  65. requires parameters.
  66.  
  67. tar [-]Commands[Options] ARCHIVE [LIST] [BLKS] [LEN] [-C DIR] file1 file2 ...
  68.  
  69. Commands:
  70.      c           create a new archive
  71.      r           append files to end of archive
  72.      t           list the contents of an archive
  73.      x           extract files from an archive
  74.  
  75. Options:
  76.      b BLKS      blocking factor BLKS (block size = BLKS x 512 bytes)
  77.      e LENGTH    maximum length of extension to use in UNIX file names
  78.      f ARCHIVE   read/write archive from file ARCHIVE (mandatory)
  79.      i           ignore checksum errors and blocks of zeros (normally EOF)
  80.      l [LIST]    read list of files from file LIST or !tarlist as default
  81.      m           don't extract file modified time
  82.      p           convert '!' in RISC OS names to '.' in UNIX names
  83.      s           swap extension in filename
  84.      v           verbosely list what files we process
  85.      w           ask for confirmation
  86.      z           run files through compress
  87.      B           reblock as we read
  88.      C DIR       change to directory DIR
  89.      E           '.' in UNIX names will be converted to '_'
  90.      F           format disk in drive 0 (multiple volumes & E-format only)
  91.      M           use multiple volume archiving
  92.      O           do not prompt for confimation when formating or overwriting disks
  93.      Q           quit immediately if error occurs, do not prompt for action
  94.      S           swap extensions in whole path
  95.      T           file types appended to names as with RISC-OS NFS
  96.      U           UNIX archive (no Archimedes extensions)
  97.      Z           convert UNIX '.Z' to '-Z' when extracting
  98.  
  99.  
  100. You must specify an archive file on the command line with the 'f' option.
  101. The path names of the archived files are stored as specified on
  102. the command line. Using the 'v' (verbose) option will list the path names
  103. stored as the archive is created. Normally you shouldn't specify the absolute
  104. path names, as you may want to extract the files to an other directory.
  105.  
  106.  
  107. 4. Normal Files As Archives
  108. ---------------------------
  109. Here the use of tar is identical to the UNIX usage. The file name of an
  110. archive must always be supplied with the 'f' option. To create an archive
  111. use the 'c' option:
  112.  
  113. tar cvf myarc file1 file2 file3
  114.  
  115. This will create an archive 'myarc' in the current directory which contains
  116. the files 'file1', 'file2' and 'file3'. I always recommend using the 'v'
  117. option with every command, this gives more information on what is happening.
  118.  
  119. You can use path names with the archives and files specified:
  120.  
  121. tar cvf adfs::4.tmp.myarc adfs::5.file1 adfs::4.src.file2
  122.  
  123. To list the contents of an archive use the 't' command:
  124.  
  125. tar tvf myarc
  126.  
  127. To extract files from an archive use the 'x' command:
  128.  
  129. tar xvf myarc
  130.  
  131. This command will extract all files in the archive. If you only want certain
  132. files, you can specify them after the archive name:
  133.  
  134. tar xvf myarc file1 file2
  135.  
  136.  
  137. 5. Hard disc backup
  138. -------------------
  139. This actually isn't very different from normal archiving. The main difference
  140. is that archive files are of course written to floppy discs and that they
  141. can be split across several discs. The command:
  142.  
  143. tar cvMf :0.backup :4.*
  144.  
  145. will backup all files on the hard disk :4 onto floppy disk :0 in the
  146. file 'backup'. If the archive requires more than one floppy disc, you will
  147. be prompted for more discs, which will contain further files also called
  148. 'backup'. They contain a header which supplies identification of the disc
  149. number so that 'tar' will be able to determine the disc sequence when
  150. extracting.
  151.  
  152. It would be better to go to the root directory of the hard disc and to use
  153. the following command:
  154.  
  155. tar cvMf :0.backup *
  156.  
  157. This will store the path names without the drive name, so you could extract
  158. them onto a different hard disk.
  159.  
  160. The command:
  161.  
  162. tar tvf :0.backup
  163.  
  164. will list the contents of an archive on floppy disc :0. If the archive was
  165. split across several discs, tar will prompt for further discs when finished
  166. listing one.
  167.  
  168. The command:
  169.  
  170. tar xvf :0.backup
  171.  
  172. will extract all files on floppy disc :0 in the file 'backup'. If the file,
  173. which is being extracted, already exists, tar will overwrite it without any
  174. warning.
  175.  
  176.  
  177. 6. Compression
  178. --------------
  179. With the 'z' option files can be compressed before being written to an archive.
  180. For compression the standard UNIX utility compress is used, also supplied with
  181. the tar programme. The system variable tar$scrap is used for temporary storage.
  182. If you are backing up a complete hard disc and have enough memory you should
  183. use a RAM disc for the scrap file, and the compress programme should also be
  184. copied onto the RAM disc. You can use different programmes for
  185. compression and decompression if you set the tar$compress and tar$decompress
  186. system variables. The default settings are:
  187.  
  188.   tar$compress          compress < %1 > %2
  189.   tar$decompress        compress -d < %1 > %2
  190.  
  191. Most compression programmes add a suffix to the compressed file. The UNIX
  192. compress programme adds '-Z'. If a compression programme that you want to use,
  193. uses a different suffix, you can set the system variable 'tar$compress$extension'.
  194.  
  195. When writing a file 'TresImp' to an archive the compress command will expand to:
  196.  
  197.   compress < TresImp > Scrap-Z
  198.  
  199. The %1 parameter is substituted with the file name and %2 is substituted with
  200. the scrap file name.
  201.  
  202. The decompress command, when extracting the file, will expand to:
  203.  
  204.   compress -d < Scrap-Z > TresImp
  205.  
  206. So if you have a compression programme 'squash' and a decompression programme
  207. 'expand', which take two parameters and don't use I/O redirection, set the
  208. variables to:
  209.  
  210.   tar$compress          squash %1 %2
  211.   tar$decompress        expand %1 %2
  212.  
  213. You can also specify absolute paths in these variables, e.g. when the
  214. compression programme is on the RAM disc:
  215.  
  216.   tar$compress          ram:$.compress < %1 > %2
  217.   tar$decompress        ram:$.compress -d < %1 > %2
  218.  
  219. Compressed files are automatically detected when extracting. A verbose listing
  220. of the archive also shows the compression percentage.
  221.  
  222. NOTE: The 'z' option is intended for hard disc backups, so that they can be
  223. compressed while being created. If you are created a normal archive file which
  224. will not be split, it is more efficient to compress the tar archive after
  225. it has been created. To do this, use the compress programme:
  226.  
  227. tar cvf myarc files...
  228. compress myarc
  229.  
  230. You will have to decompress the archive before extracting file form it.
  231.  
  232.  
  233. 7. The List File
  234. ----------------
  235. The command:
  236.  
  237. tar l tarlist
  238.  
  239. will read file names and options from the file 'tarlist' instead of the
  240. command line, if any file names are given they will be ignored, options
  241. on the command line are overridden by options specified in the 'tarlist'
  242. file. The 'tarlist' file may contain empty lines, which are ignored, lines
  243. with one file name, and lines starting with a period followed by one
  244. command or option or a blank and a comment. For example:
  245.  
  246.  
  247. . tar archive definition file (this is a comment, note blank after the period)
  248.  
  249. .c create command (stuff after .c is ignored)
  250. .v verbose option (stuff after .v is ignored)
  251. .f :0.backup (archive file name)
  252. .z compress option ( " )
  253. .b 400 blocking factor (stuff after 400 is ignored)
  254.  
  255. . file names follow
  256.  
  257. !Boot
  258. Apps.*
  259. Games.*
  260.  
  261.  
  262. This example file can be found in the distributed tar archive. If no list file
  263. name is given on the command line '!tarlist' will be used as default.
  264.  
  265.  
  266. 8. UNIX Compatibility
  267. ---------------------
  268. Another main use of the tar programme is as a file transfer programme between
  269. UNIX and RISC OS. Archives created with the 'U' option can be processed by
  270. UNIX tar programmes. The UNIX file system doesn't know anything about file
  271. types, so these will be lost when using the 'U' option. File permissions and
  272. date stamps are converted to UNIX format (this is always done, even if the
  273. 'U' option is not used, but tar will save the original RISC OS date stamps
  274. also if 'U' is not used. UNIX tar programmes which ignore extra information
  275. in the tar header will be able to process non-UNIX archives).
  276.  
  277. The RISC OS version of tar detects UNIX tar archives and converts file names to
  278. adfs. The 's' option can be used to swap the extension of a file:
  279.  
  280. RISC OS ---> UNIX:  c.test ---> test.c
  281. UNIX ---> RISC OS:  test.c ---> c.test
  282.  
  283. When converting from RISC OS to UNIX, tar will only regard directories as a file
  284. name extension if the directory name is shorter than the maximum file name
  285. extension length. This is 3 by default, but can be set with the 'e' option.
  286.  
  287. The 'Z' option converts the UNIX '.Z' suffix to a '-Z' suffix as used by the
  288. compress programme ( test.c.Z -> c.test-Z ).
  289.  
  290. The 'p' option can be used when creating a UNIX archive to translate a '!' at the
  291. beginning of a file name to '.'.
  292.  
  293. NOTE: UNIX tar archives do not support multiple disc archives! They also do not
  294.       support date stamps which are less than 1-Jan-1970.
  295.  
  296.  
  297. 9. Raw disc dumping
  298. -------------------
  299. To transfer files directly via floppy disc to a UNIX machine, you will have to
  300. create a UNIX archive which is dumped on a raw disc, i.d. a disc that is
  301. formatted but which will not contain a directory structure. The most common
  302. disc format is the MS-DOS format (2 sides, 80 tracks, 9 sectors per track).
  303.  
  304. To create a raw disc archive use the special archive name 'floppy:'. Supply
  305. the drive number after the colon. For example:
  306.  
  307. tar cvf floppy:0 files...
  308.  
  309. will create a raw disc archive in drive 0 on a E/D-format disc.
  310.  
  311. tar cvf floppy:0M files...
  312.  
  313. will create a raw disc archive in MS-DOS format.
  314.  
  315. Disc should be formatted before dumping an archive on them.
  316.  
  317. On a UNIX machine a typical command to extract an archive from floppy disc
  318. could be:
  319.  
  320. tar xvf /dev/rfd0
  321.  
  322.  
  323. 10. History
  324. -----------
  325.  
  326. 1.1o:
  327.   - Acorn tar file type &C46 is now used by default
  328.   - exit code is now 0 not 22 when writing archive
  329.   - tar sprite now for file type &C46
  330.  
  331. 1.1n
  332.   - extensions were not truncated when extracting from unix archives
  333.   - tar file type is now always used
  334.   - simple tar file sprite included in the distribution
  335.  
  336. 1.1m
  337.   - severe mess-up when truncating long unix path names corrected,
  338.     first file with directories in name which had to be created was not extracted!
  339.  
  340. 1.1l
  341.   - new 'X' option, add textual file type as extension in UNIX archives
  342.  
  343. 1.1k
  344.   - formatting is now done with *adfs:format 0 e y
  345.  
  346. 1.1j
  347.   - 'Q' option corrected, options are scanned before startup code
  348.      is performed
  349.  
  350. 1.1i
  351.   - 'T' option now works correctly with file types less than 0x100
  352.  
  353. 1.1h
  354.   - removed problems with startup-dir and archive on separate discs
  355.  
  356. 1.1g
  357.   - limit of 77 files in a directory removed
  358.   - programme now exits with Sys$ReturnCode != 0 on user interrupt
  359.     if writing an archive
  360.  
  361. 1.1f
  362.   - 'Q' option added: non-interactive mode
  363.   - 'T' option added: file type handling like RISC-OS NFS
  364.  
  365. 1.1e
  366.   - "-C" can now also be used when extracting
  367.  
  368. 1.1d
  369.   - 'M' option re-introduced, must be used for multiple disc archiving
  370.   - raw disc dumping now should be chosen with 'f' option and 'floppy:'
  371.     archive name
  372.   - prompt for confirmation when using raw disc archives,
  373.     'O' option disables confirmation
  374.   - improved 'i' option, better defective archive handling
  375.   - when creating UNIX archives, directory to file extension swapping
  376.     will only occur if 's' option is used
  377.   - 'p' option introduced, enables '!' to '.' translation
  378.   - 'F' option introduced, formats floppy in drive 0 to E-format,
  379.     intended for hard-disc backup
  380.   - new system variable tar$compress$extension enables further configuring
  381.     of the compression programme used.
  382.  
  383. 1.1a
  384.   - first release to 'comp.sys.acorn'
  385.     Now I can feel what international means...
  386.     (A tip of the magical hat to all Rush fans)
  387.   - multiple disc archiving changed, now consistent with normal use; archives
  388.     on multiple floppy discs are now ordinary files and are split into
  389.     several files on different discs; main problem was writing a
  390.     filing-system independent free-space routine (not all filing systems are
  391.     FileCore based!)
  392.   - tar$filetype introduced; when set use value as FileType for tar files,
  393.     maybe Acorn could supply a tar file type; this would be mandatory for
  394.     a desktop version
  395.   - dangerous bug with tar$scrap set to directory removed; used to delete
  396.     directory recursively, now produces error message
  397.   - bug when extracting directories 'bad file name' removed
  398.   - tar$scrap now only has to be set when using compression
  399.  
  400. 1.0o
  401.   - RISC OS to UNIX file name conversion introduced
  402.     directory names may be converted to extensions,
  403.     '!' to '.', '/' to '_'
  404.   - new list file default '!tarlist'
  405.   - compress now called with I/O redirection, saves disk space and
  406.     I/O access time
  407.  
  408. 1.0n
  409.   - UNIX/RISC-OS time conversion rewritten: FP eliminated,
  410.     minor deviations corrected, over-/underflow check
  411.   - FSVars module no longer required
  412.  
  413. 1.0l-m
  414.   - system variable for compression scrap file tar$scrap
  415.   - system variables for compression and decompression commands
  416.     tar$compress, tar$decompress
  417.  
  418. 1.0h-i
  419.   - fixed more bugs with 's' option and introduced 'Z' option
  420.  
  421. 1.0g
  422.   - fixed bug with 's' option
  423.  
  424. 1.0f
  425.   - the 'r' option is now implemented
  426.   - the 'L' type discs are now implemented
  427.   - the 'M' option was dropped, multiple disk archives are now default
  428.     expect if writing a UNIX archive, or 'O' option is used
  429.   - new 'l' option introduced, files and options can now be specified
  430.     in a LIST file
  431.   - tar now prompts for 'discs' not 'volumes'
  432.  
  433. 1.0e
  434.   - first release into the public domain in 'eunet.micro.acorn'
  435.